Release 10.1A: OpenEdge Deployment:
Managing 4GL Applications

Upgrading with updated .df and encrypted source

When you update a database structure in the development environment, you must then re-create these changes in the database that is already established at the deployment site. To accomplish this transfer, an incremental .df file is generated in the development environment. Copies of the original and updated databases are compared, and the differences between them are incorporated into an incremental .df file. For more information on creating an incremental 4GL data definitions file see OpenEdge Data Management: Database Administration . The following general steps tell you how to prepare a .df file that includes new or modified data definitions:

Obtain copies of the current user database and the new modified database.
Connect the two databases.
Compare the data definitions in the user database with the data definitions of your new updated database, creating a new incremental .df file that reflects the changes.
Provide a utility for users that loads the incremental .df file into the existing database.
Encrypt the procedures affected by changed data definitions.

To prepare a data definitions file:

In Windows, open the Data Administration Tool (for character interfaces, open the Data Dictionary).
Connect the two databases by choosing Database Connect.
Select the database that includes the new, modified data definitions as your current database by choosing Database Select Working Database.
Create an incremental definition file by choosing Admin Dump Data and Definitions Create Incremental .df File.

This option compares the data definitions in the non-empty copy to the current database schema and creates a new data definition (.df) file. The new .df file contains a record for each difference between the two schemas. The differences include any added, renamed, changed, or deleted file, field, or index.

If a file, field, or index exists in the old database but not in the new schema, OpenEdge asks you whether the object has been renamed. If you respond no, a record appears in the new .df file marking the object as deleted.

If the new schema includes a new unique active index, OpenEdge asks you whether you want to deactivate it. If you do not deactivate the index, and there are duplicate keys in the old database, OpenEdge aborts your attempt to load new definitions into the old database. If you deactivate the index, the load procedure defines the new index, but does not create the index file. You must build and activate the index after loading the new data definitions.

Perform steps a through d below for testing purposes. Then prepare a tool for users that performs these steps on site:
Note: The upgrade template provided with OpenEdge outlines one way to do this. Before you can use this template, you probably need to modify it.
Select the copy of the old database as your working database.
Load the updated data definitions by choosing Admin Load Data and Definitions Load Data Definitions (.df file).
If you deactivated any indexes in Step 3, re-create data in the indexed fields as required to avoid duplicate keys. Then reactivate the indexes with PROUTIL IDXBUILD. For more information, see OpenEdge Data Management: Database Administration .
OpenEdge now updates the old database schema to match the modified schema. Compile and test all your procedures against the updated database.
Test your procedures.
Use the XCODE utility to encrypt procedures invalidated by the new data definitions.

Since the new .df file changes CRC check sums and time-stamps only on the database tables that are actually modified, you only have to encrypt and ship the source versions of those procedures that access the changed tables. (If you compile your procedures with the XREF option, you get a listing of the tables accessed by each procedure.)

Using the upgrade template

The upgrade template, all .p files it uses, and all .inp files it uses are only templates; you must check each file and modify it to suit your particular application. Following is a list of checks and modifications you must make before using upgrade; your application might require additional changes.

The UNIX version of upgrade is found in /usr/dlctk/samples/unix. The DOS version is located in the respective subdirectories of samples. The files that upgrade uses can be found in /usr/dlctk/samples.

The upgrade template performs three basic actions to upgrade an application at the user’s site:

Loads the new .df file, which you created from your version of the upgraded database with the Admin Dump Data and Definitions Create Incremental .df File option.
Rebuilds any indexes deactivated during the data definition load process.
Compiles encrypted source procedures.

Changes to the upgrade template for the data definition load stage (Step 1.):

Modify upgrade.p (not the upgrade template) and the files it uses:
Set the system administrator ID and password appropriately in loginupg.p (or prepare a tool your users can use to set them).
Modify upgrade.inp to name the new .df file.
Test load_df.p (a standard OpenEdge Dictionary procedure). If you have created a new unique active index, load_df.p asks whether you want to deactivate the index. You need to add a response (Y or N) to upgrade.inp.
If you and your users do not freeze the database files, delete the call to freeze.p. (Leave the call to unfreeze.p in case your users ever freeze the database files without your knowledge.)
Modify unfreeze.p and freeze.p to include the correct filenames.
Check upgrade.log for any problems.

Changes to the upgrade template for the rebuild deactivated indexes stage (Step 2.):

If you and your users will not be deactivating indexes, remove the _proutil command line from upgrade.
If you have added a new unique active index, modify rebuild.inp to include the correct responses to prompts by _proutil $1 -C idxbuild. That is, test _proutil idxbuild on your database and add a line to rebuild.inp to answer each question appropriately.
Check rebuild.log for problems.
You might want to add a procedure to upgrade that checks rebuild.log and, if necessary, fixes duplicate key data and rebuilds the index again. Alternatively, you might want to check the .log file and just stop before compilation proceeds.

Changes to upgrade template for the compile encrypted procedures stage (Step 3.):

Modify compile.inp to name the procedures to be compiled.
Modify the COMPILE statement in compile.p to use the encryption key you want.
Prepare to ship compile.p: either encrypt compile.p, possibly with the default key, or compile compile.p, thereby hiding your encryption key in the .r file. If you ship compile.r, it must be compiled on the target machine type. It can be compiled against any database because it does not reference any database files.

The upgrade template is relevant when you want to distribute only new data definitions and encrypted versions of affected application procedures. However, you might choose instead to ship a complete new version of the database and application, as described in the following section.